The Atari Compendium/The Atari Compendium (Toad Computers) (1994).iso/files/umich/telecomm/fnordadl/fn132src.zoo/ref-man/theory.tex

Text File | 1991-09-02 | 26.7 KB | 669 lines

@comment Tell Emacs to use -*-texinfo-*- mode
@comment $Id: theory.tex,v 2.4 91/09/01 23:04:49 royce Exp $

@node Sysop Theory, User Command Reference, Fifteen Minute Guide, Top
@chapter Sysop Theory
@cindex Theory
@cindex Sysop theory

Before getting into the nitty-gritty details of what buttons to push
to get which results, let us first force down your throat some theory about
what you're going to be dealing with.  You can forget about it after the
final exam, if you wish.

@node Your Callers, Rooms, Sysop Theory, Sysop Theory
@section Your Callers
@cindex Callers
@cindex Users, types of

You are presumably going through all of this because you
wish to have people of some type call your system and do something
with it.  These callers are your reason for running a @sc{bbs}.  While
other systems offer a vast array of access and status levels,
the general Citadel philosophy of simplicity holds here, meaning
that there are no real preferential user access levels.

Despite that fact, there do need to be some ways to handle
special cases.  @xref{User Status Commands}, for the commands to assign the
various user attributes.  As of this writing, the attributes are:

@itemize @bullet
@item
@cindex Sysop
@dfn{The Sysop}.  That's you, the System Operator, and there's only one of you
unless you share the duties with other people, or
somebody else has access to your computer while it's
running Fnordadel.  You can do anything within reason,
and a few things beyond reason.  Fnordadel allows you to define
the name used by the Sysop in @file{ctdlcnfg.sys}, using the parameter
@vindex sysop
@code{#sysop}.  You should set this up correctly.  (If your system really
has more than one Sysop, set the
@vindex sysop
@code{#sysop} parameter to whichever one
has direct access to the system or uses the system most, or just pick a name
from a hat.  Alternatively, leave
@vindex sysop
@code{#sysop} undefined.
@xref{The Sysop Command Reference}, for more discussion on Sysop matters.)

@item
@cindex Co-Sysop
@dfn{Co-Sysops}.  You may additionally designate any number of other
users on your system as ``Co-Sysops'', by assigning them Sysop privileges.
This means that they have virtually
unlimited ability to use any command, @emph{except} those in the
Sysop menu (accessed by @samp{^L} at the main room prompt).
To let such people have access to the Sysop menu as well, you need
to give them the system password.  Note that anyone who has
been given Sysop privs is also automatically given Aide privs.

@item
@cindex Aide
@dfn{Aides}.  These are people that you wish to have help you
operate, maintain and control your system.  They can do things
like delete, copy or move messages, and they may do a certain
amount of room editing, floor maintenance and other things.  In
general, however, they can't do much to change the basic nature
of things (e.g. alter networking parameters, do things involving
access to your storage devices, etc.).

@item
@cindex Twit
@dfn{Twits}.  These are users that you have decided are too
detrimental to have continued access to your system, but
whose user accounts you don't simply wish to kill, lest
they immediately sign back on again and continue where
they left off.  Twits have most commands disabled; this
includes the ability to post messages!

@item
Everybody else.  This is the group of people who are
not the Sysop, Co-Sysops, Aides, or Twits.  They comprise the bulk of
your user population, most likely.
@end itemize

Additionally, the Sysop has control over users' ability to do certain things like
send private mail, create new discussion rooms, and post in
networked rooms.  (Such rooms may well be connected to long-distance
systems, and we don't want irresponsible or evil
users causing big phone bills!)

When you first start your system, it is unlikely that you will
wish to grant Aide or Co-Sysop status to many of your users, since you probably
won't know many of them at all well.  Our advice is to take your time, and
pick out some people who will handle the positions responsibly.  If chosen
wisely, they will be an asset in controlling your system, and in making
creative contributions which prevent stagnation.

@node Rooms, Floors, Your Callers, Sysop Theory
@section Rooms
@cindex Rooms

Right from the start, Citadel made use of something called a
@cindex Room
@dfn{room} to contain messages on a related topic.  Fnordadel does
the same.  A room has a name up to 19 characters in length, which
presumably captures the gist of a topic to be discussed by the
messages in that room.  Some systems you may be familiar with make
use of ``message areas'', ``message bases'', ``SIGs'' (Special Interest
Groups), etc.  They are all basically analogous to rooms, but will
typically be few in number and cover broad, static topics.

Other systems make use of ``threads'', in which messages are
related to each other by a common subject field (for example) rather
than physical location.  Callers travel up and down the threads one
message at a time, and now and then jump to a new thread.  Still
other systems have no way to organise messages; they are all stored
in one giant mass that is hard to wade through as a user, and still
preserve one's sanity.

We feel that Citadel's room metaphor is much easier to use
than a threading scheme, offers better organization than one massive
message area, and permits better dynamic flow of discussion than
bulky SIGs or message bases.

As callers use your system, they will move from room to room
reading new messages, and posting replies as they see fit.  If the
topic of a room drifts off on a tangent (as is common), you as
Sysop may exercise control to bring it back on track, change its
name to suit the new trend of discussion, move the off-topic messages
into a newly-created room, or kill the room entirely if none of the
above options are worth the effort.

The basic room can be specialised in a number of ways to
meet various needs.  Some of the attributes are:

@itemize @bullet
@item
@cindex Permanent (room type)
@dfn{Permanent}.  Normally, empty rooms will be purged by the
system from time to time.  There is also a command for
doing this explicitly (see @code{.A(ide) D(elete-empty-rooms)} in
@ref{The .A(ide) command}).  You may
not always wish rooms to disappear if they go empty, so
you may designate them permanent, and they will stick
around.

@item
@cindex Anonymous (room type)
@dfn{Anonymous}.  Rooms of this type are used for discussions
where callers may wish to remain totally unidentified.
None of the usual message header information is stored or
shown by the system, just a message number.

@item
@cindex Private (room type)
@dfn{Private}.  These rooms are for carrying out activities
that are not to be viewed by all callers to the system.
Only users who are told of the complete room name are
able to get into it.  And once a user knows the room's
name, he can't be barred from it short of altering the
name and reinviting all the other users.

@item
@cindex Invitation-only (room type)
@dfn{Invitation-only}.  These rooms are just like the above
type, with one difference.  Users must be invited into
them with a system command; knowing the full name is not
sufficient to gain access.  If a caller's presence is no
longer desired, eviction from the room is also easily
possible, without choosing a new room name.

@item
@cindex Read-only (room type)
@dfn{Read-only}.  Rooms of this type can only have messages
entered in them by the Sysop, Co-Sysops or Aides.  A typical use for
such a room is for announcements that you wish people to
have access to, uncluttered by comments from other callers.

@item
@cindex Directory (room type)
@dfn{Directory}.  Rooms of this type are used to give callers
access to your storage device(s) (@sc{ram}, disk or hard drives),
for the purposes of file uploading and/or downloading.
Each directory room is tied to a specific disk directory
somewhere, so you can give different people access to
different collections of files.  Normal discussion
activities are permissable in directory rooms.

@item
@cindex Network (room type)
@cindex Shared (room type)
@dfn{Network} or @dfn{Shared}.  Rooms of this type are linked via the
Citadel network (or any other supported) to other systems
that also carry the same rooms.  Messages entered in
these rooms will be transferred among all the systems
sharing the room, thus permitting a much larger cross-section
of callers to participate in the discussion, no
matter their geographical locations.
@end itemize

Note that these attributes can be mixed, so it is possible to
have, say, a shared, directory, read-only, private, anonymous, permanent room.

In order to distinguish between the different types of room that can
be found, Fnordadel adds a special character following the room name in many
places where room names are shown.  They are as follows:

@table @samp
@item ]
designates a directory room
@item )
designates a shared (network) room
@item :
designates a shared directory room
@item >
designates all other types of room
@end table

From time to time in the following chapters, you will see references
to the term
@cindex Room prompt
@dfn{room prompt}.  The room prompt is where users are sitting
on the
system when nothing is going on, and Fnordadel is waiting for a command to
be entered.  It's called the @emph{room} prompt because the system displays the
name of the room in which the user is sitting.

@node Floors, Scrolling, Rooms, Sysop Theory
@section Floors
@cindex Floors

Some years after the development of Citadel, numerous
systems were getting to be quite large.  Rooms permit the organization
of messages, but when there are 50 and more rooms, they need to be
organized themselves.  Thus
@dfn{floors} were developed, and are to rooms
as rooms are to messages: rooms group related messages, while
floors group related rooms.

If callers choose not to operate in floor mode, they will
see your system as it would have been before floors came about.  If
@cindex Floor mode
they choose floor mode, however, they will see collections of rooms
through which they can navigate, in addition to normal room-to-room
movement.  This permits efficient activites with groups of rooms.
Usually all rooms on a floor are somehow related, just as all messages
in a room are related.  The advantage of this is extra organization
that doesn't get in anybody's way.  Even if floor mode is chosen by
a user, it does not add any inconvenience to his/her use of the system.

@node Scrolling, Modes of Operation, Floors, Sysop Theory
@section Scrolling
@cindex Scrolling
@cindex Wrap-around

@dfn{Scrolling} is a term commonly used to describe the way
many aspects of a Citadel work.  A good mental
image of scrolling is simply to picture any circular, oval, or
otherwise closed, race-track.  Racers on the track start at the
beginning, and loop around it forever after, unless somebody or
something stops them.

A number of things in Fnordadel also scroll.  The largest
is probably going to be the message file, which is where all the
messages entered in all the rooms are kept.  Messages get placed into
it at the beginning, and continue being added until the physical end
of the file is reached.  At this time Fnordadel (and all Citadels)
loops back to the start and overwrites old messages there with
continued new entries.  In this fashion, your system efficiently
organizes all messages on your storage device for you, and also
automatically deletes old messages.

If you find that the message file scrolls faster than you
would like, increase its size with the @code{mexpand} utility (see
@pindex mexpand
@file{mexpand.man}).  Conversely, if the file is not scrolling fast enough,
@pindex mshrink
decrease its size with the @code{mshrink} utility (see @file{mshrink.man}).

Another thing that scrolls is your user file.  This file
contains all information known about your users, and has space for
a fixed number of users, which you specify.  When that space is
used up, the next new user to sign onto your system will cause the
user file to scroll.  The system picks the user who has not signed
on for the longest period of time, and tosses the account to make
room for the new arrival.  Again, efficient use of storage, and no
maintenance for the Sysop.  (Note that the system will scroll you
and your Aides and Co-Sysops with equal efficiency, so be sure you all
sign on regularly!)

Room contents are yet another thing that --- you guessed it ---
scroll.  This is because the messages in rooms get overwritten by
the scrolling action of the main message file.  Thus room content
is always current to one degree or another (it depends how large the
message file is), and the Sysop doesn't have to lift a finger to
keep things that way.

@node Modes of Operation, Configuring, Scrolling, Sysop Theory
@section Modes of Operation
@cindex Modes of operation

Fnordadel has four distinct modes of operation, and it's
a good idea to understand what the differences are, since they
determine who can do what when.

@node Modem mode, Console mode, Modes of Operation, Modes of Operation
@subsection Modem mode
@cindex Modem mode

When you are not using the system, which is hopefully
most of the time (unless you really like reading your own
commentary), Fnordadel is in @dfn{modem mode}.  All this means is
that it is ignoring almost everything typed at the console,
and is either handling commands entered by a user who called, or
else waiting for a call to come in.

There are only two ways out of modem mode.  The most
common is for you, the Sysop, to hit the @samp{<ESC>} key at the
console, and enter console mode (see below).  The other is
for the software to crash in flames.  Fortunately, the latter
never happens.

@node Console mode, Chat mode, Modem mode, Modes of Operation
@subsection Console mode
@cindex Console mode

When you are using the system, Fnordadel is in
@dfn{console mode} (unless you dialed in from elsewhere, but that's
cheating).  It is possible for the system to be in console
mode while a user is connected from remote.  It is advised
that you not enter console mode, however, except when the user
is at a room prompt.  Otherwise, strange things may happen
when you hit @samp{<ESC>} to take over.

When the system is in console mode, you can carry out
normal @sc{bbs} activites such as reading and entering messages.
If nobody is logged in, Fnordadel may restrict what you can
do based on some of the settings in @file{ctdlcnfg.sys}.  See
@file{ctdlcnfg.doc} for details.  In any case, being in console mode
will let you do most things, logged in or not, plus it also
gets you access to the Sysop special functions menu without having
to enter the system password.  @xref{The Sysop Command Reference}, for
more details.

To return the system to modem mode --- which you must
do in order for it to receive calls again, or for an online
user to finish what he or she was up to --- use the @code{[M]odem mode}
command in the Sysop menu.  Again, see @ref{The Sysop Command Reference}.

@node Chat mode, Network mode, Console mode, Modes of Operation
@subsection Chat mode
@cindex Chat mode

@dfn{Chat mode} is unlike the two previous modes in two ways.
First, Fnordadel pays attention to characters coming in from
both the console and the modem, and echoes all of them to the
screen.  This is how you talk to your users when they're on the
system.  Try it, you might like it!

Second, virtually no commands are available in chat
mode.  It is intended for purely discussion purposes.  To exit
chat mode, hit @samp{<ESC>}.  Fnordadel will return to either modem
or console mode according to what mode was in effect when chat
mode was started.  If the mode is console, don't forget to
return Fnordadel to modem mode so the user can finish his or
her activities.

Chat mode is also used when you dial out from your
system and connect with other systems as a user, yourself.  In
these cases you're chatting with another @sc{bbs} instead of a user.
If you press @samp{<ESC>} while still online with a remote system,
you'll probably want to reconnect with it once you've finished
whatever caused you to hit @samp{<ESC>}.  To do this, just execute the
@code{[C]hat} command yourself, or use the
@code{[G]otomodem@dots{}} command from the
Sysop menu.  @xref{Other room prompt commands}, and
@ref{Sysop Special Functions}, for details.

@node Network mode,  , Chat mode, Modes of Operation
@subsection Network mode
@cindex Network mode

@dfn{Network mode} is unlike the previous three modes, in that
nobody is logged in to the system.  Instead, it is communicating
with other Citadel(s) of some kind, somewhere, for the purpose of
transferring private mail, shared rooms, files, and so on.  When
the system is in networking mode, nobody else can use it until it
finishes what needs doing.  Clearly, the more time your system
spends networking, the less time your users and yourself can be
online.  So configure your network controls to give a good
balance between system availability and timely communication
with your networking partners.

@node Configuring, Command Structure, Modes of Operation, Sysop Theory
@section Configuring
@cindex Configuring

If you read @ref{Fifteen Minute Guide}, on how to start your system
as quickly as possible, you will have encountered the instructions to
modify a file called @file{ctdlcnfg.sys} and run a program called
@code{configur}.
@pindex configur
Here is more treatment of that information, or a first look if you
skipped that chapter like someone who wants to get all the facts before
mucking with things.

@node ctdlcnfg.sys, configur, Configuring, Configuring
@subsection The ctdlcnfg.sys file
@cindex ctdlcnfg.sys (file)

This is the Fnordadel configuration file, an @sc{ascii}
text file that can be edited with any text editor or word
processor which can output @sc{ascii} files.  It contains a truck-load
of system parameters and options that let you tell
Fnordadel things it needs to know, and let you set up some
non-essentials to give your system a unique flavour.  For
details on the contents of this file, see @file{ctdlcnfg.doc}.

Please be sure that the contents of this file always
accurately describe your system!  There are utility programs
that will modify various parameters of your system, but they
@emph{do not} alter the contents of @file{ctdlcnfg.sys}.  It is up to you to
edit the file and change the appropriate values.  If you don't,
@emph{pure evil} will result.

In order for the information in this file to actually
get communicated to Fnordadel, it must be run through the
configuration program, @code{configur}.  Speaking of which @dots{}

@node configur, ctdltabl.sys, ctdlcnfg.sys, Configuring
@subsection The configur program
@pindex configur

@code{configur} is the Fnordadel configuration program.  It
processes everything you've entered in @file{ctdlcnfg.sys} and
checks for errors of omission or commission, displaying
error messages as necessary.  The error messages will hopefully
pin-point the problem for you.  You can always look
at @file{ctdlcnfg.doc} for a (bloated) example of a correct file.

If everything goes well, the result of running this
program will be yet another file called @file{ctdltabl.sys}.

@node ctdltabl.sys,  , configur, Configuring
@subsection The ctdltabl.sys file
@cindex ctdltabl.sys (file)

This is the file which contains the distilled
essence of @file{ctdlcnfg.sys}, in a binary form that Fnordadel can
accept; it also contains various system tables (like indices
into the message file, log file and so on) which change with
time.  Fnordadel will not run if this file is not present,
and it will die horribly or act terribly if the file is
incomplete, corrupted, or otherwise screwed up.  Likewise with
many of the Fnordadel utility programs.

For this reason, Fnordadel and some of the more
complex utility programs will actually delete @file{ctdltabl.sys}
when you run them, and then write it back out again when they
exit properly. This prevents the ugly situation, for example,
of running your Fnordadel for a few days, and having it
crash messily, leaving around a @file{ctdltabl.sys} that no longer
reflects the current status of your system.  If you tried to
rerun your system without reconfiguring, it would be a Very
Bad Thing.

As things stand, a bad crash by Fnordadel or a
utility will leave you without @file{ctdltabl.sys}, forcing you
to rerun @code{configur} before doing anything else.
@pindex configur

This point bears emphasis: @emph{losing your @file{ctdltabl.sys}
file means almost nothing}.  You can always regenerate it by
running @code{configur}, as long as no other system files have
been damaged or deleted.  If you suspect anything weird is
going on with your system, the first thing you should do is
@emph{back everything up}, and @emph{not} over top of an existing backup.
The second thing to do is delete @file{ctdltabl.sys} and run
@code{configur}.  Hopefully this will fix things up.

@node Command Structure,  , Configuring, Sysop Theory
@section Command Structure
@cindex Command structure

Before we start with particular groups of commands, let's
look at the structure of Citadel commands.  One design
feature of the command system is ``orthogonality'', which is a nice
big word that roughly means ``consistency''.  Or, things look the
same one place as in another.  Keep this in mind and it will speed
you on your way to mastering the system's complexity.

Keep one other thing in mind:  At almost every conceivable
point in the system where it is waiting for you to enter a command,
you can press the @samp{?} key to see a list of the currently available
commands.  ``This system of menus isn't quite as convenient as ones
that pop up automatically as with other @sc{bbs}es'', argue some people,
but it is another facet of Citadel's philosophy --- stay out of the
way unless called for.

And now, the two basic types of commands.

@node About single-key commands, About extended commands, Command Structure, Command Structure
@subsection Single-key commands
@cindex Single-key commands

The so-called @dfn{single-key} commands are the basic
bread and butter for you and your users.  They are the
common functions that everybody wants to use all of the
time, and they have been streamlined as much as possible
to permit people to do what they want without wading though
layers of barriers (what other systems call ``menus'').  These
commands are all invoked by pressing a single key, and do
not need to be followed by a carriage-return.

To be a successful Fnordadel user, you only have
to know five of the single-key commands:

@itemize @bullet
@item
@code{[G]oto the next room}

@item
@code{read [N]ew messages}

@item
@code{[E]nter a message}

@item
@code{[P]ause reading}

@item
@code{[S]top reading}
@end itemize

These five commands, along with the obvious need to
know @code{[L]ogin}, @code{[?]} and @code{[T]erminate}, will satisfy most
people who call.

@node About extended commands,  , About single-key commands, Command Structure
@subsection Multi-key/extended commands
@cindex Extended commands
@cindex Multi-key commands

It would be nice if all functions of the software
could be called up using single key-strokes.  Fortunately---yes, that's
``fortunately''---there
are too many of them to permit this.  For example,
there are those individuals who will want to be able to do
things like compose messages (probably long ones) off-line
and then upload them in one shot to your board.  There
will be those people who will want to grab whatever
downloadable files you've got on your board.  There will be
those who want to upload stuff to your board.  (I know, it's
hard to believe, but there is the occasional altruistic soul
around.)  And, naturally, there will be those individuals
who will want to do some odd variant of any of those things,
or a host of others.  Yourself, Co-Sysops, and Aides are
probably good examples of such people.

To accommodate this need, Fnordadel uses @dfn{multi-key}
or @dfn{extended}, commands.  In contrast to the single-key
commands, multi-key commands start with a mode character
and are followed by a number of other command characters.
Some extended commands also take a user name, file name or
date; these must be terminated by a carriage return.

The mode character tells Fnordadel that you're
using an extended command instead of a single-key command,
and what type of extended command it will be.  Normal
extended commands that deal with rooms, messages and files
start with a period, @samp{.}.  Floor extended commands, which
deal with entire floors, start with a semi-colon, @samp{;}.
Door extended commands, which permit the running of other
programs from within Fnordadel, start with an exclamation
mark, @samp{!}.

Most extended commands will either be ``enter'' or
``read'' operations.  Citadel defines any command you use
that results in data being sent to the system as an
``enter'' command.  Any command that results in data being
sent from the system to you is a ``read'' command.

Thus, to read new messages in the current room, you
could use the extended command

@example
.rn
@end example

@noindent
which the system will display as:

@example
.read new
@end example

To download a file @file{blort.txt} using the Xmodem file transfer
protocol, you would also do a read operation:

@example
.rxfblort.txt<CR>
@end example

@noindent
which is displayed like:

@example
.read xmodem file blort.txt
@end example

@noindent
followed by an ``are you ready'' sort of prompt.

To get even trickier, you could download all new messages
in the current room from the user ``Foobar'' since 90Jul01, to
your own system, using the Ymodem file transfer protocol, for
leisurely perusal:

@example
.ryu+nFoobar<CR>89Jul01<CR>
@end example

@noindent
which looks like:

@example
.read ymodem user after new - which user: Foobar
After what date: 89Jul01
@end example

You may not notice, but in all these cases, there is a
pattern to the command.  It always starts with a @samp{.}, then
specifies the main command followed by some options, and
finishes with what the command is supposed to deal with
(``new'' implies ``new messages'', while ``file'' explicitly means
``files'').  The system will then prompt for further data as
needed by some of the options.  To summarize the structure:

@example
@var{<mode>} @var{<main command>} @var{<options>} @var{<what to process>}
@var{<prompts for any additional data>}
@end example

In the final example above, @samp{.ryu+n}, we have:

@table @var
@item <mode>
@samp{.} for ``extended command''
@item <main command>
@samp{r} for ``read''
@item <options>
@samp{yu+} for ``ymodem user after''
@item <what to process>
@samp{n} for ``new messages''
@item <prompts>
``which user'' and ``After what date''
@end table

This patterning, which aids a user in knowing what
to expect and even helps him/her to anticipate how commands
should be strung together, is the ``orthogonality'' mentioned
before.  Orthogonal command structures always do the same
or similar things in the same way, or by using the same
structure.  It is one of the strengths of Citadel, and one
of the glaring weaknesses of many other systems.  It makes
your system look unlike anything you or your users may have
encountered before, but we think it's worth it.